
<html><HEAD>
<LINK REL=STYLESHEET HREF="default.css" TYPE="text/css">
<TITLE>
Working with nested reports </TITLE>
</HEAD>
<BODY>

<!-- Header -->
<p class="ancestor" align="right"><A HREF="pbugp222.htm">Previous</A>&nbsp;&nbsp;<A HREF="pbugp224.htm" >Next</A>
<!-- End Header -->
<A NAME="BFCBAGGB"></A><h1>Working with nested reports </h1>
<A NAME="TI7526"></A><p>When you use nested reports either in composite reports or
in other base reports, several enhancements and options are available.
An easy way to see what you can do is to select the nested report
and look at the Properties view for it. </p>
<A NAME="TI7527"></A><p>Many of the options in the Properties view are described in <A HREF="pbugp175.htm#CAICGCGD">Chapter 19, "Enhancing DataWindow Objects ."</A> For example,
using borders on nested reports is like using borders on any control.</p>
<A NAME="TI7528"></A><p>This section describes activities that apply only to nested
reports or that have special meaning for nested reports. It covers:<A NAME="TI7529"></A>
<ul>
<li class=fi><A HREF="pbugp223.htm#BFCBIHGI">"Adjusting nested report
width and height"</A></li>
<li class=ds><A HREF="pbugp223.htm#BFCDCJDA">"Changing a nested report
from one report to another"</A></li>
<li class=ds><A HREF="pbugp223.htm#BFCCDAFB">"Modifying the definition
of a nested report"</A></li>
<li class=ds><A HREF="pbugp223.htm#BFCBBACA">"Adding another nested report
to a composite report"</A></li>
<li class=ds><A HREF="pbugp223.htm#BFCDIAGD">"Supplying retrieval arguments
to relate a nested report to its base report"</A></li>
<li class=ds><A HREF="pbugp223.htm#BFCDEGGE">"Specifying criteria to relate
a nested report to its base report"</A></li>
<li class=ds><A HREF="pbugp223.htm#BFCCIAGD">"Using options for nested
reports"</A>
</li>
</ul>
</p>
<A NAME="BFCBIHGI"></A><h2>Adjusting nested report width and height</h2>
<A NAME="TI7530"></A><p>When you preview a report with nested reports, the width of
the nested report may be unacceptable. This can happen, for example,
if you change the design of the nested report or if you use newspaper
columns in a nested report. The width of the nested
report is not adjusted to fit its contents at runtime; if the report
is too narrow, some columns may be truncated. For example, if the
size of the nested report is set to 6 inches wide in the parent
report, columns in the nested report that exceed that width are
not displayed in the parent report.</p>
<A NAME="TI7531"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To adjust report width:</p>
<ol><li class=fi><p>In the Design view, position the pointer
near a vertical edge of the nested report and press the left mouse
button.</p></li>
<li class=ds><p>Drag the edge to widen the nested report.</p></li>
<li class=ds><p>Check the new width in the Preview view.</p></li></ol>
<br><A NAME="TI7532"></A><p>When you Print preview a DataWindow that contains a nested
N-Up report with newspaper columns across the page, you might find
that blank pages display (and print) when the nested report in the
detail band fills the page. This is because any white space at the
bottom of the band is printed to a second page. You can usually
solve this problem by dragging up the detail band to eliminate the
white space between the nested report and the band, or even to overlap
the bottom of the representation of the nested report.</p>
<A NAME="BFCDCJDA"></A><h2>Changing a nested report from one report to another</h2>
<A NAME="TI7533"></A><p>You can change the nested report that is used. For example,
you may work on several versions of a nested report and need to
update the version of the nested report that the composite or base
report uses.</p>
<A NAME="TI7534"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To change the nested report to a different report:</p>
<ol><li class=fi><p>Select the nested report in the Design
view.</p></li>
<li class=ds><p>In the Properties view, General property page,
click the button next to the Report box.</p></li>
<li class=ds><p>Select the report you want to use, and click OK.</p><p>The name of the report that displays in the box in the Design
view changes to the new one.</p></li></ol>
<br><A NAME="BFCCDAFB"></A><h2>Modifying the definition of a nested report</h2>
<A NAME="TI7535"></A><p>You can modify the definition of the nested report. You can
do this directly from the composite report or base report that contains
the nested report.</p>
<A NAME="TI7536"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To modify the definition of a nested report from
the composite report or base report:</p>
<ol><li class=fi><p>Position the pointer on the nested report
whose definition you want to modify, and display the pop-up menu.</p></li>
<li class=ds><p>Select Modify Report from the pop-up menu.</p><p>The nested report opens and displays in the painter. Both
the composite or base report and the nested report are open.</p></li>
<li class=ds><p>Modify the report.</p></li>
<li class=ds><p>Select File&gt;Close from the menu bar.</p><p>You are prompted to save your changes.</p></li>
<li class=ds><p>Click OK.</p><p>You return to the composite report or to the base report that
includes the nested report.</p></li></ol>
<br><A NAME="BFCBBACA"></A><h2>Adding another nested report to a composite report</h2>
<A NAME="TI7537"></A><p>After you have created a composite report, you might want
to add another report. The following procedure describes how. For information
on adding a nested report to a report that is <i>not</i> a
composite report, see <A HREF="pbugp222.htm#BFCCACGF">"Placing a related nested
report in another report"</A> or <A HREF="pbugp222.htm#BFCDGAHG">"Placing an unrelated nested
report in another report"</A>.</p>
<A NAME="TI7538"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To add another nested report to a composite report:</p>
<ol><li class=fi><p>Open the composite report.</p></li>
<li class=ds><p>Select Insert&gt;Control&gt;Report
from the menu bar.</p></li>
<li class=ds><p>Click in the Design view where you want to place
the report.</p><p>The Select Report dialog box displays, listing defined reports (DataWindow
objects) in the current target's library search path.</p></li>
<li class=ds><p>Select the report you want and click OK.</p><p>A box representing the report displays in the Design view.</p></li></ol>
<br><A NAME="BFCDIAGD"></A><h2>Supplying retrieval arguments to relate a nested report to its base report</h2>
<A NAME="TI7539"></A><p>The most efficient way to relate a nested report to its base
report is to use retrieval arguments. If your nested report has
arguments defined, you use the procedure described in this section
to supply the retrieval argument value from the base report to the
nested report. (The procedure described is part of the whole process
covered in <A HREF="pbugp222.htm#BFCCACGF">"Placing a related nested
report in another report"</A>.)</p>
<A NAME="TI7540"></A><h4>Why retrieval arguments are efficient</h4>
<A NAME="TI7541"></A><p>Some DBMSs have the ability to bind input variables in the <b>WHERE</b> clause
of the <b>SELECT</b> statement. When you use retrieval
arguments, a DBMS <i>with this capability</i> sets
up placeholders in the <b>WHERE</b> clause and compiles
the <b>SELECT</b> statement <i>once</i>. PowerBuilder retains
this compiled form of the <b>SELECT</b> statement for
use in subsequent retrieval requests.</p>
<A NAME="TI7542"></A><h4>Requirements for reusing the compiled SELECT
statement</h4>
<A NAME="TI7543"></A><p>To enable PowerBuilder to retain and reuse the compiled <b>SELECT</b> statement:<A NAME="TI7544"></A>
<ul>
<li class=fi>The database interface must
support binding of input variables.</li>
<li class=ds>You must enable binding support by setting the DisableBind
database parameter to 0, which is the default.</li>
<li class=ds>You must enable caching in the database profile.
Set the <ACRONYM title = "sequel" >SQL</ACRONYM>Cache database parameter
to the number of levels of nesting plus 5.<br>
For more information, see the description
of the <ACRONYM title = "sequel" >SQL</ACRONYM>Cache and DisableBind
database parameters in the online Help.<br>
</li>
</ul>
</p>
<p><img src="images/note.gif" width=17 height=17 border=0 align="bottom" alt="Note"> <span class=shaded>Nested reports in composite reports</span> <A NAME="TI7545"></A>If the base report is a composite report, you need to define
retrieval arguments for the composite report before you can supply
them to the nested report. </p>
<A NAME="TI7546"></A>In the Properties view for the composite report, select the
General page. Then define the retrieval arguments that the nested
report needs, taking care to specify the correct type.</p>
<A NAME="TI7547"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To supply a retrieval argument value from the
base report to the nested report:</p>
<ol><li class=fi><p>Make sure that the nested report has been
set up to take one or more retrieval arguments.</p><p>See <A HREF="pbugp222.htm#BFCBAJDF">"Placing a nested report
in another report "</A>.</p></li>
<li class=ds><p>Select the nested report and then select the General
page of the Properties view.</p><p>The Arguments box lists arguments defined for the nested report
and provides a way for you to specify how information from the base
report will supply the value of the argument to the nested report.</p><br><img src="images/nest15a.gif"><br>
</li>
<li class=ds><p>Supply the base report column or the expression
that will supply the argument's value. To do this, click the
button in the Expression column.</p><p>The Modify Expression dialog box displays. In this dialog
box, you can easily select one of the columns or develop an expression. In
the example, the column named <b>id</b> from the base
report will supply the value for the argument <i>:customerid</i> in
the nested report.</p><p>When you run the report now, you are not prompted for retrieval
argument values for the nested report. The base report supplies
the retrieval argument values automatically.</p></li></ol>
<br><A NAME="BFCDEGGE"></A><h2>Specifying criteria to relate a nested report to its base report</h2>
<A NAME="TI7548"></A><p>If you do not have arguments defined for the nested report
and if database efficiency is not an issue, you can place a nested
report in another report and specify criteria to pass values to
the related nested report.</p>
<A NAME="TI7549"></A><h4>How the DBMS processes <ACRONYM title = "sequel" >SQL</ACRONYM> if
you use the specify criteria technique</h4>
<A NAME="TI7550"></A><p>If you use the specify criteria technique, the DBMS repeatedly
recompiles the <b>SELECT</b> statement and then executes
it. The recompilation is necessary for each possible variation of
the <b>WHERE</b> clause.</p>
<A NAME="TI7551"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To specify criteria to relate a nested report
to its base report:</p>
<ol><li class=fi><p>Select the nested report and then select
the Criteria page in the Properties view.</p><p>The Criteria property page provides a way for you to specify
how information from the base report will supply the retrieval criteria
to the nested report.</p></li>
<li class=ds><p>Click the button next to the criteria box.</p><p>The Specify Retrieval Criteria dialog box displays.</p></li>
<li class=ds><p>Enter the retrieval criteria and click OK.</p><p>The rules for specifying criteria are the same as for specifying
criteria in the Quick Select data source. Multiple criteria in one
line are <b>AND</b>ed together. Criteria entered on
separate lines are <b>OR</b>ed together.</p><p>In this example, the customer ID (the <b>id</b> column)
is the retrieval criterion being supplied to the nested report. </p><p>Notice that the <b>id</b> column is preceded
by a colon (:), which is required:</p><br><img src="images/nest28.gif"><br>
<p>When you run the report now, PowerBuilder retrieves rows in
the nested report based on the criteria you have specified. In the
example, the customer ID column in the base report determines which
rows from the <b>sales_order</b> table are
included for each customer.</p></li></ol>
<br><A NAME="BFCCIAGD"></A><h2>Using options for nested reports</h2>
<A NAME="TI7552"></A><h4>Using the Autosize Height option</h4>
<A NAME="TI7553"></A><p>Autosize Height should be on for all nested reports except
graphs. This option ensures that the height of the nested report
can change to accommodate the rows that are returned.</p>
<A NAME="TI7554"></A><p>This option is on by default for all nested reports except
graphs. Usually there is no reason to change it. If you do want
to force a nested report to have a fixed height, you can turn this
option off.</p>
<A NAME="TI7555"></A><p>Note that all bands in the DataWindow also have an Autosize
Height option. The option is off by default and must be on for the Autosize
Height option for the nested report to work properly.</p>
<A NAME="TI7556"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To change the Autosize Height option for a nested
report:</p>
<ol><li class=fi><p>In the Design view, select the nested report.</p></li>
<li class=ds><p>In the Properties view, select the Position properties
page.</p></li>
<li class=ds><p>Select/clear the Autosize Height check
box.</p></li></ol>
<br><p><img src="images/note.gif" width=17 height=17 border=0 align="bottom" alt="Note"> <span class=shaded>Handling large rows</span> <A NAME="TI7557"></A>To avoid multiple blank pages or other anomalies in printed
reports, never create a DataWindow object with a data row greater than
the size of the target page. To handle large text-string columns,
break the large string into a series of small strings. The smaller
strings are used to populate individual data rows within a nested
report instead of using a single text column with an autosized height. </p>
<A NAME="TI7558"></A><h4>Using the Slide options</h4>
<A NAME="TI7559"></A><p>PowerBuilder determines the appropriate Slide options when positioning
the nested report(s) and assigns default values. Usually, you should
not change the default values:<A NAME="TI7560"></A>
<ul>
<li class=fi>The Slide Left option is on by default for grid
and crosstab style reports and off by default for all others. Having
Slide Left on for grid and crosstab ensures that these reports break
horizontally on whole columns and not in the middle of a column.</li>
<li class=ds>The Slide Up All Above and Directly Above options
ensure that the nested report uses just as much vertical space as
it needs. One of these options is on by default for all nested reports.
</li>
</ul>
</p>
<A NAME="TI7561"></A><p>For more information, see <A HREF="pbugp184.htm#BFCDCEHJ">"Sliding controls to remove
blank space in a DataWindow object"</A>.</p>
<A NAME="TI7562"></A><h4>Using the New Page option (composite only)</h4>
<A NAME="TI7563"></A><p>The New Page option forces a new page for a nested report
used <i>in a composite report</i>. By default, this
option is off.</p>
<A NAME="TI7564"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To specify that a nested report in a composite
report should begin on a new page:</p>
<ol><li class=fi><p>In the Design view, select the nested report.</p></li>
<li class=ds><p>In the Properties view, select the General properties
page.</p></li>
<li class=ds><p>Select the New Page check box.</p></li></ol>
<br><A NAME="TI7565"></A><h4>Using the Trail Footer option (composite only)</h4>
<A NAME="TI7566"></A><p>The Trail Footer option controls the placement of the footer
for the last page of a nested report <i>in a composite report</i>.
By default, this option is on. The footer appears directly under
the contents of the nested report and not at the bottom of the page.</p>
<A NAME="TI7567"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To specify that the footer should appear at the
bottom of the page:</p>
<ol><li class=fi><p>In the Design view, select the nested report.</p></li>
<li class=ds><p>In the Properties view, select the General properties
page.</p></li>
<li class=ds><p>Clear the Trail Footer check box.</p></li>
<li class=ds><p>The footer appears at the bottom of the page on all
pages of the nested report, including the last page. Note that if
another nested report begins on the same page, the footer from the
earlier report might be misleading or confusing.</p></li></ol>
<br>
